<!DOCTYPE html>
<html lang="en" dir="ltr" class="client-nojs">
<head>
<meta charset="UTF-8" />
<title>Cpfind - PanoTools.org Wiki</title>
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<meta name="generator" content="MediaWiki 1.23.6" />






<style media="screen" type="text/css" title="Screen style sheet"> @import url(manual.css); </style>

<style>a:lang(ar),a:lang(kk-arab),a:lang(mzn),a:lang(ps),a:lang(ur){text-decoration:none}
/* cache key: panotools_wiki:resourceloader:filter:minify-css:7:90730a7865ba4b50e0b837e1821ff0a3 */</style>



<!--[if lt IE 7]><style type="text/css">body{behavior:url("/skins/vector/csshover.min.htc")}</style><![endif]--></head>
<body class="mediawiki ltr sitedir-ltr ns-0 ns-subject page-Cpfind skin-vector action-view vector-animateLayout">
		
		
		<div id="content" class="mw-body" role="main">
			<a id="top"></a>
			
						<h1 id="firstHeading" class="firstHeading" lang="en"><span dir="auto">Cpfind</span></h1>
						<div id="bodyContent">
								<div id="siteSub">From PanoTools.org Wiki</div>
								
												
				<div id="mw-content-text" lang="en" dir="ltr" class="mw-content-ltr"><div id="toc" class="toc"><div id="toctitle"><h2>Contents</h2></div>
<ul>
<li class="toclevel-1 tocsection-1"><a href="Cpfind.html#General_and_description"><span class="tocnumber">1</span> <span class="toctext">General and description</span></a></li>
<li class="toclevel-1 tocsection-2"><a href="Cpfind.html#Usage"><span class="tocnumber">2</span> <span class="toctext">Usage</span></a>
<ul>
<li class="toclevel-2 tocsection-3"><a href="Cpfind.html#Rectilinear_and_fisheye_images"><span class="tocnumber">2.1</span> <span class="toctext">Rectilinear and fisheye images</span></a></li>
<li class="toclevel-2 tocsection-4"><a href="Cpfind.html#Using_celeste"><span class="tocnumber">2.2</span> <span class="toctext">Using celeste</span></a></li>
<li class="toclevel-2 tocsection-5"><a href="Cpfind.html#Matching_strategy"><span class="tocnumber">2.3</span> <span class="toctext">Matching strategy</span></a>
<ul>
<li class="toclevel-3 tocsection-6"><a href="Cpfind.html#All_pairs"><span class="tocnumber">2.3.1</span> <span class="toctext">All pairs</span></a></li>
<li class="toclevel-3 tocsection-7"><a href="Cpfind.html#Linear_match"><span class="tocnumber">2.3.2</span> <span class="toctext">Linear match</span></a></li>
<li class="toclevel-3 tocsection-8"><a href="Cpfind.html#Multirow_matching"><span class="tocnumber">2.3.3</span> <span class="toctext">Multirow matching</span></a></li>
<li class="toclevel-3 tocsection-9"><a href="Cpfind.html#Matching_overlapping_images_.28prealigned_panorama.29"><span class="tocnumber">2.3.4</span> <span class="toctext">Matching overlapping images (prealigned panorama)</span></a></li>
<li class="toclevel-3 tocsection-10"><a href="Cpfind.html#Keypoints_caching_to_disc"><span class="tocnumber">2.3.5</span> <span class="toctext">Keypoints caching to disc</span></a></li>
</ul>
</li>
</ul>
</li>
<li class="toclevel-1 tocsection-11"><a href="Cpfind.html#Extended_options"><span class="tocnumber">3</span> <span class="toctext">Extended options</span></a>
<ul>
<li class="toclevel-2 tocsection-12"><a href="Cpfind.html#Feature_description"><span class="tocnumber">3.1</span> <span class="toctext">Feature description</span></a></li>
<li class="toclevel-2 tocsection-13"><a href="Cpfind.html#Feature_matching"><span class="tocnumber">3.2</span> <span class="toctext">Feature matching</span></a></li>
</ul>
</li>
</ul>
</div>

<h1><span class="mw-headline" id="General_and_description">General and description</span></h1>
<p><b>Cpfind</b> is a control point detector for <a href="Hugin.html" title="Hugin">hugin</a>. It expects a project file as input and write a project file with control points on success. The general usage is
</p>
<pre>     cpfind -o output.pto input.pto
</pre>
<p>Internal the control point detector algorithm is divided into 2 parts: 
</p>
<ul>
<li> The first step is the feature description: In this step the images of the project file are loaded and so called keypoints are searched. They describe distinctive features in the image. Cpfind is using a gradient based descriptor for the feature description of the keypoints. 
</li>
<li> In a second step, the feature matching, all keypoints of two images are matched against each other to find features which are on both images. If this matching was successful two keypoints in the two images become one control point.
</li>
</ul>
<h1><span class="mw-headline" id="Usage">Usage</span></h1>
<h2><span class="mw-headline" id="Rectilinear_and_fisheye_images">Rectilinear and fisheye images</span></h2>
<p>Cpfind can find control points in rectilinear and fisheye images. To achieve good control points images with a high horizontal field of view (e.g. ultra wide rectilinear or fisheye) are therefore remapped into a conformal space (cpfind is using the stereographic projection<a class="external" href="http://wiki.panotools.org/Projection#Stereographic_projection">[*]</a>) and the feature matching occurs in this space. Before writing the control points the coordinates are remapped back to the image space. This happens automatic depending on the information about the lens in the input project file. So check that your input project file contains reasonable information about the used lens.
</p>
<h2><span class="mw-headline" id="Using_celeste">Using celeste</span></h2>
<p>Outdoor panorama often contains clouds. Clouds are bad areas for setting control points because they are moving object. Cpfind can use the same algorithm as <a href="Celeste_standalone.html" title="Celeste standalone">celeste_standalone</a> to masked out areas which contains clouds. (This is only done internal for the keypoint finding step and does not change the alpha channel of your image. If you want to generate a mask image use <a href="Celeste_standalone.html" title="Celeste standalone">celeste_standalone</a>). To run cpfind with celeste use
</p>
<pre>   cpfind --celeste -o output.pto input.pto
</pre>
<p>Using <b>cpfind</b> with integrated celeste should be superior against using <b>cpfind</b> and <a href="Celeste_standalone.html" title="Celeste standalone">celeste_standalone</a> sequential. When running <b>cpfind with celeste</b> areas of clouds, which often contains keypoints with a high quality measure, are disregarded and areas without clouds are used instead. When running <b>cpfind without celeste</b> also keypoints on clouds are found. When afterwards running <a href="Celeste_standalone.html" title="Celeste standalone">celeste_standalone</a> these control points are removed. In the worst case all control points of a certain image pair are removed.
</p><p>So running <b>cpfind with celeste</b> leads to a better "control point quality" for outdoor panorama (e.g. panorama with clouds). Running <b>cpfind with celeste</b> takes longer than <b>cpfind</b> alone. So for indoor panorama this option does not need to specified (because of longer computation time).
</p><p>The celeste step can be fine tuned by the parameters --celesteRadius and --celesteThreshold.
</p>
<h2><span class="mw-headline" id="Matching_strategy">Matching strategy</span></h2>
<h3><span class="mw-headline" id="All_pairs">All pairs</span></h3>
<p>This is the default matching strategy. Here all image pairs are matched against each other. E.g. if your project contains 5 images then <b>cpfind</b> matches the image pairs: 0-1, 0-2, 0-3, 0-4, 1-2, 1-3, 1-4, 2-3, 2-4 and 3-4
</p><p>This strategy works for all shooting strategy (single-row, multi-row, unordered). It finds (nearly) all connected image pairs. But it is computational expensive for projects with many images, because it test many image pairs which are not connected.
</p>
<h3><span class="mw-headline" id="Linear_match">Linear match</span></h3>
<p>This matching strategy works best for single row panoramas:
</p>
<pre>   cpfind --linearmatch -o output.pto input.pto
</pre>
<p>This will only detect matches between adjacent images, e.g. for the 5 image example it will matches images pairs 0-1, 1-2, 2-3 and 3-4. The matching distance can be increased with the switch --linearmatchlen. E.g. with --linearmatchlen 2 <b>cpfind</b> will match a image with the next image and the image after next, in our example it would be 0-1, 0-2, 1-2, 1-3, 2-3, 2-4 and 3-4.
</p>
<h3><span class="mw-headline" id="Multirow_matching">Multirow matching</span></h3>
<p>This is an optimized matching strategy for single and multi-row panorama:
</p>
<pre>   cpfind --multirow -o output.pto input.pto
</pre>
<p>The algorithm is the same as described in <a href="Hugin_Parameters_for_Control_Point_Detectors_dialog.html#Multi-row_panorama" title="Hugin Parameters for Control Point Detectors dialog">multi-row panorama</a>. By integrating this algorithm into <b>cpfind</b> it is faster by using several cores of modern CPUs and don't caching the keypoints to disc (which is time consuming). If you want to use this multi-row matching inside <a href="Hugin.html" title="Hugin">hugin</a> set the control point detector type to <a href="Hugin_Parameters_for_Control_Point_Detectors_dialog.html#All_images_at_once" title="Hugin Parameters for Control Point Detectors dialog">All images at once</a>, this is so that Hugin passes all images to cpfind and lets cpfind apply the multirow matching smarts itself.
</p>
<h3><span class="mw-headline" id="Matching_overlapping_images_.28prealigned_panorama.29">Matching overlapping images (prealigned panorama)</span></h3>
<p>This setting is for finding control points in panorama, in which the rough positions of the images are already known (e.g. when using a template or when generating the pto file by a script)
</p>
<pre>   cpfind --prealigned -o output.pto input.pto
</pre>
<p>This algorithm does only matches images pairs, which overlaps and don't already have control point. All other image pairs are ignored.
</p><p>The algorithm is the same as described in <a href="Hugin_Parameters_for_Control_Point_Detectors_dialog.html#Prealigned_panorama" title="Hugin Parameters for Control Point Detectors dialog">prealigned control point detector setting</a>. By integrating this algorithm into <b>cpfind</b> it is faster by using several cores of modern CPUs and don't caching the keypoints to disc (which is time consuming). If you want to use this prealigned matching inside <a href="Hugin.html" title="Hugin">hugin</a> set the control point detector type to <a href="Hugin_Parameters_for_Control_Point_Detectors_dialog.html#All_images_at_once" title="Hugin Parameters for Control Point Detectors dialog">All images at once</a>.
</p>
<h3><span class="mw-headline" id="Keypoints_caching_to_disc">Keypoints caching to disc</span></h3>
<p>The calculation of keypoints takes some time. So <b>cpfind</b> offers the possibility to save the keypoints to a file and reuse them later again. With --kall the keypoints for all images in the project are saved to disc. If you only want the keypoints of particular image use the parameter -k with the image number:
</p>
<pre>   cpfind --kall input.pto
   cpfind -k 0 -k 1 input.pto
</pre>
<p>The keypoint files are saved by default into the same directory as the images with the extension .key. In this case no matching of images occurs and therefore no output project file needs to specified. If <b>cpfind</b> finds keyfiles for an image in the project it will use them automatically and not run the feature descriptor again on this image.
If you want to save them to another directory use the --keypath switch. 
</p><p>This procedure can also be automate with the switch --cache:
</p>
<pre>   cpfind --cache -o output.pto input.pto
</pre>
<p>In this case it tries to load existing keypoint files. For images, which don't have a keypoint file, the keypoints are detected and saved to the file. Then it matches all loaded and newly found keypoints and writes the output project.
</p><p>If you don't need the keyfile longer, the can be deleted automatic by
</p>
<pre>   cpfind --clean input.pto
</pre>
<h1><span class="mw-headline" id="Extended_options">Extended options</span></h1>
<h2><span class="mw-headline" id="Feature_description">Feature description</span></h2>
<p>For speed reasons <b>cpfind</b> is using images, which are scaled to their half width and height, to find keypoints. With the switch --fullscale <b>cpfind</b> is working on the full scale images. This takes longer but can provide "better" and/or more control points.
</p><p>The feature description step can be fine-tuned by the parameters:
</p><p>--sieve1width &lt;int&gt;           Sieve 1: Number of buckets on width (default: 10)
</p><p>--sieve1height &lt;int&gt;          Sieve 1: Number of buckets on height (default: 10)
</p><p>--sieve1size &lt;int&gt;            Sieve 1: Max points per bucket (default: 100)
</p><p>--kdtreesteps &lt;int&gt;           KDTree: search steps (default: 200)
</p><p>--kdtreeseconddist &lt;double&gt;   KDTree: distance of 2nd match (default: 0.25)
</p><p><b>Cpfind</b> stores maximal sieve1width * sieve1height * sieve1size keypoints per image. If you have only a small overlap, e.g. for 360 degree panorama shoot with fisheye images, you can get better results if you increase sieve1size. You can also try to increase sieve1width and/or sieve1height.
</p><p>Effectively cpfind splits your image in rectangles or buckets: sieve1width horizontally by sieve1height vertically. It will try to find sieve1size keypoints per bucket. This ensures a reasonably uniform distribution of interest points over your image. These features will be matched in the matching step. With the default parameters, up to 10000 interest points will be used in the feature matching step.
</p>
<h2><span class="mw-headline" id="Feature_matching">Feature matching</span></h2>
<p>Fine-tuning of the matching step by the following parameters:
</p><p>--ransaciter &lt;int&gt;            <a rel="nofollow" class="external text" href="http://en.wikipedia.org/wiki/RANSAC">Ransac</a>: iterations (default: 1000)
</p><p>--ransacdist &lt;int&gt;            Ransac: homography estimation distance threshold (pixels) (default: 25)
</p><p>--ransacmode &lt;string&gt;        Select the mode used in the ransac step. Possible values: auto, hom, rpy, rpyv, rpyb (default: auto)
</p>
<ul>
<li> hom: Assume a homography. Only applicable for non-wide angle views. Uses the original panomatic code. It is also more flexible than required and can generate false matches, particularly if most of the matches are located on a single line.
</li>
</ul>
<ul>
<li> rpy: Align images using roll, pitch and yaw. This requires a good estimate for the horizontal field of view (and distortion, for  heavily distorted images). It is the preferred mode if a calibrated lens is used, or the HFOV could be read successfully from the EXIF data.
</li>
</ul>
<ul>
<li> rpyv: Align pair by optimizing roll, pitch, yaw and field of view. Should work without prior knowledge of the field of view, but might fail more often, due to error function used in the panotools optimizer, it tends to shrink the fov to 0.
</li>
</ul>
<ul>
<li> rpyvb: Align pair by optimizing roll, pitch, yaw, field of view and the "b" distortion parameter.  Probably very fragile, just implemented for testing.
</li>
</ul>
<ul>
<li> auto: Use homography for images with hfov &lt; 65 degrees and rpy otherwise.
</li>
</ul>
<p>--minmatches &lt;int&gt;            Minimum matches (default: 4)
</p><p>--sieve2width &lt;int&gt;           Sieve 2: Number of buckets on width (default: 5)
</p><p>--sieve2height &lt;int&gt;          Sieve 2: Number of buckets on height (default: 5)
</p><p>--sieve2size &lt;int&gt;            Sieve 2: Max points per bucket (default: 1)
</p><p><b>Cpfind</b> generates between minmatches and sieve2width * sieve2height * sieve2size control points between an image pair. (Default setting is between 4 and 25 (=5*5*1) control points per image pair.) 
If less then minmatches control points are found for a given image pairs these control points are disregarded and this image pair is considered as not connected. For narrow overlaps you can try to decrease minmatches, but this increases the risk of getting wrong control points.
This filtering step (sieve2) works similar like sieve1 step described above: The rectangular area, which is covered by control points, is divided into sieve2width * sieve2height rectangles/buckets - sieve1width horizontally by sieve1height vertically. For each bucket only sieve2size control points are saved in the project file. This step is intended to get an uniform distribution of the control points.
</p>



</div>								<div class="printfooter">
				Retrieved from "http://wiki.panotools.org/index.php?title=Cpfind&amp;oldid=14282<a class="external" href="http://wiki.panotools.org/index.php?title=Cpfind&amp;oldid=14282">[*]</a>"				</div>
												</div></div></body></html>